home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / program / nasm095s.zip / NASM.DOC < prev    next >
Text File  |  1997-07-27  |  73KB  |  1,770 lines

  1.              The Netwide Assembler, NASM
  2.              ===========================
  3.  
  4. Introduction
  5. ============
  6.  
  7. The Netwide Assembler grew out of an idea on comp.lang.asm.x86 (or
  8. possibly alt.lang.asm, I forget which), which was essentially that
  9. there didn't seem to be a good free x86-series assembler around, and
  10. that maybe someone ought to write one.
  11.  
  12. - A86 is good, but not free, and in particular you don't get any
  13.   32-bit capability until you pay. It's DOS only, too.
  14.  
  15. - GAS is free, and ports over DOS/Unix, but it's not very good,
  16.   since it's designed to be a back end to gcc, which always feeds it
  17.   correct code. So its error checking is minimal. Also its syntax is
  18.   horrible, from the point of view of anyone trying to actually
  19.   _write_ anything in it. Plus you can't write 16-bit code in it
  20.   (properly).
  21.  
  22. - AS86 is Linux specific, and (my version at least) doesn't seem to
  23.   have much (or any) documentation.
  24.  
  25. - MASM isn't very good. And it's expensive. And it runs only under
  26.   DOS.
  27.  
  28. - TASM is better, but still strives for MASM compatibility, which
  29.   means millions of directives and tons of red tape. And its syntax
  30.   is essentially MASM's, with the contradictions and quirks that
  31.   entails (although it sorts out some of those by means of Ideal
  32.   mode). It's expensive too. And it's DOS only.
  33.  
  34. So here, for your coding pleasure, is NASM. At present it's still in
  35. prototype stage - we don't promise that it can outperform any of
  36. these assemblers. But please, _please_ send us bug reports, fixes,
  37. helpful information, and anything else you can get your hands on
  38. (and thanks to the many people who've done this already! You all
  39. know who you are), and we'll improve it out of all recognition.
  40. Again.
  41.  
  42. Please see the file `Licence' for the legalese.
  43.  
  44. Getting Started: Installation
  45. =============================
  46.  
  47. NASM is distributed in source form, in what we hope is totally
  48. ANSI-compliant C. It uses no non-portable code at all, that we know
  49. of. It ought to compile without change on any system you care to try
  50. it on. We also supply a pre-compiled 16-bit DOS binary.
  51.  
  52. To install it, edit the Makefile to describe your C compiler, and
  53. type `make'. Then copy the binary to somewhere on your path. That's
  54. all - NASM relies on no files other than its own executable.
  55. Although if you're on a Unix system, you may also want to install
  56. the NASM manpage (`nasm.1'). You may also want to install the binary
  57. and manpage for the Netwide Disassembler, NDISASM (also see
  58. `ndisasm.doc').
  59.  
  60. Running NASM
  61. ============
  62.  
  63. To assemble a file, you issue a command of the form
  64.  
  65.     nasm -f <format> <filename> [-o <output>]
  66.  
  67. For example,
  68.  
  69.     nasm -f elf myfile.asm
  70.  
  71. will assemble `myfile.asm' into an ELF object file `myfile.o'. And
  72.  
  73.     nasm -f bin myfile.asm -o myfile.com
  74.  
  75. will assemble `myfile.asm' into a raw binary program `myfile.com'.
  76.  
  77. To produce a listing file, with the hex codes output from NASM
  78. displayed on the left of the original sources, use `-l' to give a
  79. listing file name, for example:
  80.  
  81.     nasm -f coff myfile.asm -l myfile.lst
  82.  
  83. To get further usage instructions from NASM, try typing `nasm -h'.
  84. This will also list the available output file formats, and what they
  85. are.
  86.  
  87. If you use Linux but aren't sure whether your system is a.out or
  88. ELF, type `file /usr/bin/nasm' or wherever you put the NASM binary.
  89. If it says something like
  90.  
  91. /usr/bin/nasm: ELF 32-bit LSB executable i386 (386 and up) Version 1
  92.  
  93. then your system is ELF, and you should use `-f elf' when you want
  94. NASM to produce Linux object files. If it says
  95.  
  96. /usr/bin/nasm: Linux/i386 demand-paged executable (QMAGIC)
  97.  
  98. or something similar, your system is a.out, and you should use `-f
  99. aout' instead.
  100.  
  101. Like Unix compilers and assemblers, NASM is silent unless it goes
  102. wrong: you won't see any output at all, unless it gives error
  103. messages.
  104.  
  105. If you define an environment variable called NASM, the program will
  106. interpret it as a list of extra command-line options, processed
  107. before the real command line. This is probably most useful for
  108. defining an include-file search path by putting a lot of `-i'
  109. options in the NASM variable.
  110.  
  111. The variable's value will be considered to be a space-separated list
  112. of options unless it begins with something other than a minus sign,
  113. in which case the first character will be taken as the separator.
  114. For example, if you want to define a macro whose value has a space
  115. in it, then setting the NASM variable to `-dNAME="my name"' won't
  116. work because the string will be split at the space into `-dNAME="my'
  117. and `name"', but setting it to `|-dNAME="my name"' will be fine
  118. because all further operands will be considered to be separated by
  119. vertical bars and so the space has no special meaning.    
  120.  
  121. Quick Start for MASM Users
  122. ==========================
  123.  
  124. If you're used to writing programs with MASM, or with TASM in
  125. MASM-compatible (non-Ideal) mode, or with A86, this section attempts
  126. to outline the major differences between MASM's syntax and NASM's.
  127. If you're not already used to MASM, it's probably worth skipping
  128. this section.
  129.  
  130. One simple difference is that NASM is case-sensitive. It makes a
  131. difference whether you call your label `foo', `Foo' or `FOO'. If
  132. you're assembling to the `obj' MS-DOS output format (or `os2'), you
  133. can invoke the `UPPERCASE' directive (documented below, in the
  134. Output Formats section) and ensure that all symbols exported to
  135. other code modules are forced to uppercase; but even then, _within_
  136. a single module, NASM will distinguish between labels differing only
  137. in case.
  138.  
  139. There are also differences in some of the instructions and register
  140. names: for example, NASM calls the floating-point stack registers
  141. `st0', `st1' and so on, rather than MASM's `ST(0)' notation or A86's
  142. simple numeric `0'. And NASM doesn't support LODS, MOVS, STOS, SCAS,
  143. CMPS, INS, or OUTS, but only supports the size-specified versions
  144. LODSB, MOVSW, SCASD and so on.
  145.  
  146. The _major_ difference, though, is the absence in NASM of variable
  147. typing. MASM will notice when you declare a variable as `var dw 0',
  148. and will remember that `var' is a WORD-type variable, so that
  149. instructions such as `mov var,2' can be unambiguously given the WORD
  150. size rather than BYTE or DWORD. NASM doesn't and won't do this. The
  151. statement `var dw 0' merely defines `var' to be a label marking a
  152. point in memory: no more and no less. It so happens that there are
  153. two bytes of data following that point in memory before the next
  154. line of code, but NASM doesn't remember or care. If you want to
  155. store the number 2 in such a variable, you must specify the size of
  156. the operation _always_: `mov word [var],2'. This is a deliberate
  157. design decision, _not_ a bug, so please could people not send us
  158. mail asking us to `fix' it...
  159.  
  160. The above example also illustrates another important difference
  161. between MASM and NASM syntax: the use of OFFSET and of square
  162. brackets. In MASM, declaring `var dw 0' entitles you to code `mov
  163. ax,var' to get at the _contents_ of the variable, and you must write
  164. `mov ax,offset var' to get the _address_ of the variable. In NASM,
  165. `mov ax,var' gives you the address, and to get at the contents you
  166. must code `mov ax,[var]'. Again, this is a deliberate design
  167. decision, since it brings consistency to the syntax: `mov ax,[var]'
  168. and `mov ax,[bx]' both refer to the contents of memory and both have
  169. square brackets, whereas neither `mov ax,bx' nor `mov ax,var' refers
  170. to memory contents and so neither one has square brackets.
  171.  
  172. This is even more confusing in A86, where declaring a label with a
  173. trailing colon defines it to be a `label' as opposed to a `variable'
  174. and causes A86 to adopt NASM-style semantics; so in A86, `mov
  175. ax,var' has different behaviour depending on whether `var' was
  176. declared as `var: dw 0' or `var dw 0'. NASM is very simple by
  177. comparison: _everything_ is a label. The OFFSET keyword is not
  178. required, and in fact constitutes a syntax error (though you can
  179. code `%define offset' to suppress the error messages if you want),
  180. and `var' always refers to the _address_ of the label whereas
  181. `[var]' refers to the _contents_.
  182.  
  183. As an addendum to this point of syntax, it's also worth noting that
  184. the hybrid-style syntaxes supported by MASM and its clones, such as
  185. `mov ax,table[bx]', where a memory reference is denoted by one
  186. portion outside square brackets and another portion inside, are also
  187. not supported by NASM. The correct syntax for the above is `mov
  188. ax,[table+bx]'. Likewise, `mov ax,es:[di]' is wrong and `mov
  189. ax,[es:di]' is right.
  190.  
  191. Writing Programs with NASM
  192. ==========================
  193.  
  194. Each line of a NASM source file should contain some combination of
  195. the four fields
  196.  
  197. LABEL:    INSTRUCTION    OPERANDS    ; COMMENT
  198.  
  199. `LABEL' defines a label pointing to that point in the source. There
  200. are no restrictions on white space: labels may have white space
  201. before them, or not, as you please. The colon after the label is
  202. also optional. (Note that NASM can be made to give a warning when it
  203. sees a label which is the only thing on a line with no trailing
  204. colon, on the grounds that such a label might easily be a mistyped
  205. instruction name. The command line option `-w+orphan-labels' will
  206. enable this feature.)
  207.  
  208. Valid characters in labels are letters, numbers, `_', `$', `#', `@',
  209. `~', `?', and `.'. The only characters which may be used as the
  210. _first_ character of an identifier are letters, `_' and `?', and
  211. (with special meaning: see `Local Labels') `.'. An identifier may
  212. also be prefixed with a $ sign to indicate that it is intended to be
  213. read as an identifier and not a reserved word; thus, if some other
  214. module you are linking with defines a symbol `eax', you can refer to
  215. `$eax' in NASM code to distinguish it from the register name.
  216.  
  217. `INSTRUCTION' can be any machine opcode (Pentium and P6 opcodes, FPU
  218. opcodes, MMX opcodes and even undocumented opcodes are all
  219. supported). The instruction may be prefixed by LOCK, REP, REPE/REPZ
  220. or REPNE/REPNZ, in the usual way. Explicit address-size and operand-
  221. size prefixes A16, A32, O16 and O32 are provided - one example of
  222. their use is given in the `Unusual Instruction Sizes' section below.
  223. You can also use a segment register as a prefix: coding `es mov
  224. [bx],ax' is equivalent to coding `mov [es:bx],ax'. We recommend the
  225. latter syntax, since it is consistent with other syntactic features
  226. of the language, but for instructions such as `lodsb' there isn't
  227. anywhere to put a segment override except as a prefix. This is why
  228. we support it.
  229.  
  230. The `INSTRUCTION' field may also contain some pseudo-opcodes: see
  231. the section on pseudo-opcodes for details.
  232.  
  233. `OPERANDS' can be nonexistent, or huge, depending on the
  234. instruction, of course. When operands are registers, they are given
  235. simply as register names: `eax', `ss', `di' for example. NASM does
  236. _not_ use the GAS syntax, in which register names are prefixed by a
  237. `%' sign. Operands may also be effective addresses, or they may be
  238. constants or expressions. See the separate sections on these for
  239. details.
  240.  
  241. `COMMENT' is anything after the first semicolon on the line,
  242. excluding semicolons inside quoted strings.
  243.  
  244. Of course, all these fields are optional: the presence or absence of
  245. the OPERANDS field is required by the nature of the INSTRUCTION
  246. field, but any line may contain a LABEL or not, may contain an
  247. INSTRUCTION or not, and may contain a COMMENT or not, independently
  248. of each other.
  249.  
  250. Lines may also contain nothing but a directive: see `Assembler
  251. Directives' below for details.
  252.  
  253. NASM can currently not handle any line longer than 1024 characters.
  254. This may be fixed in a future release.
  255.  
  256. Floating Point Instructions
  257. ===========================
  258.  
  259. NASM has support for assembling FPU opcodes. However, its syntax is
  260. not necessarily the same as anyone else's.
  261.  
  262. NASM uses the notation `st0', `st1', etc. to denote the FPU stack
  263. registers. NASM also accepts a wide range of single-operand and
  264. two-operand forms of the instructions. For people who wish to use
  265. the single-operand form exclusively (this is in fact the `canonical'
  266. form from NASM's point of view, in that it is the form produced by
  267. the Netwide Disassembler), there is a TO keyword which makes
  268. available the opcodes which cannot be so easily accessed by one
  269. operand. Hence:
  270.  
  271.     fadd st1    ; this sets st0 := st0 + st1
  272.     fadd st0,st1    ; so does this
  273.     fadd st1,st0    ; this sets st1 := st1 + st0
  274.     fadd to st1    ; so does this
  275.  
  276. It's also worth noting that the FPU instructions that reference
  277. memory must use the prefixes DWORD, QWORD or TWORD to indicate what
  278. size of memory operand they refer to.
  279.  
  280. NASM, in keeping with our policy of not trying to second-guess the
  281. programmer, will _never_ automatically insert WAIT instructions into
  282. your code stream. You must code WAIT yourself before _any_
  283. instruction that needs it. (Of course, on 286 processors or above,
  284. it isn't needed anyway...)
  285.  
  286. NASM supports specification of floating point constants by means of
  287. `dd' (single precision), `dq' (double precision) and `dt' (extended
  288. precision). Floating-point _arithmetic_ is not done, due to
  289. portability constraints (not all platforms on which NASM can be run
  290. support the same floating point types), but simple constants can be
  291. specified. For example:
  292.  
  293. gamma    dq 0.5772156649        ; Euler's constant
  294.  
  295. Pseudo-Opcodes
  296. ==============
  297.  
  298. Pseudo-opcodes are not real x86 machine opcodes, but are used in the
  299. instruction field anyway because that's the most convenient place to
  300. put them. The current pseudo-opcodes are DB, DW, DD, DQ and DT,
  301. their uninitialised counterparts RESB, RESW, RESD, RESQ and REST,
  302. the INCBIN command, the EQU command, and the TIMES prefix.
  303.  
  304. DB, DW, DD, DQ and DT work as you would expect: they can each take
  305. an arbitrary number of operands, and when assembled, they generate
  306. nothing but those operands. All three of them can take string
  307. constants as operands. See the `Constants' section for details about
  308. string constants.
  309.  
  310. RESB, RESW, RESD, RESQ and REST are designed to be used in the BSS
  311. section of a module: they declare _uninitialised_ storage space.
  312. Each takes a single operand, which is the number of bytes, words or
  313. doublewords to reserve. We do not support the MASM/TASM syntax of
  314. reserving uninitialised space by writing `DW ?' or similar: this is
  315. what we do instead. (But see `Critical Expressions' for a caveat on
  316. the nature of the operand.)
  317.  
  318. (An aside: if you want to be able to write `DW ?' and have something
  319. vaguely useful happen, you can always code `? EQU 0'...)
  320.  
  321. INCBIN is borrowed from the old Amiga assembler Devpac: it includes
  322. a binary file verbatim into the output file. This can be handy for
  323. (for example) including graphics and sound data directly into a game
  324. executable file. It can be called in one of these three ways:
  325.  
  326.     INCBIN "file.dat"               ; include the whole file
  327.     INCBIN "file.dat",1024          ; skip the first 1024 bytes
  328.     INCBIN "file.dat",1024,512      ; skip the first 1024, and
  329.                                     ; actually include at most 512
  330.  
  331. EQU defines a symbol to a specified value: when EQU is used, the
  332. LABEL field must be present. The action of EQU is to define the
  333. given label name to the value of its (only) operand. This definition
  334. is absolute, and cannot change later. So, for example,
  335.  
  336. message db 'hello, world'
  337. msglen  equ $-message
  338.  
  339. defines `msglen' to be the constant 12. `msglen' may not then be
  340. redefined later. This is not a preprocessor definition either: the
  341. value of `msglen' is evaluated _once_, using the value of `$' (see
  342. the section `Expressions' for details of `$') at the point of
  343. definition, rather than being evaluated wherever it is referenced
  344. and using the value of `$' at the point of reference. Note that the
  345. caveat in `Critical Expressions' applies to EQU too, at the moment.
  346.  
  347. Finally, the TIMES prefix causes the instruction to be assembled
  348. multiple times. This is partly NASM's equivalent of the DUP syntax
  349. supported by MASM-compatible assemblers, in that one can do
  350.  
  351. zerobuf: times 64 db 0
  352.  
  353. or similar, but TIMES is more versatile than that. TIMES takes not
  354. just a numeric constant, but a numeric _expression_, so one can do
  355. things like
  356.  
  357. buffer: db 'hello, world'
  358.         times 64-$+buffer db ' '
  359.  
  360. which will store exactly enough spaces to make the total length of
  361. `buffer' up to 64. (See the section `Critical Expressions' for a
  362. caveat on the use of TIMES.) Finally, TIMES can be applied to
  363. ordinary opcodes, so you can code trivial unrolled loops in it:
  364.  
  365.     times 100 movsb
  366.  
  367. Note that there is no effective difference between `times 100 resb
  368. 1' and `resb 100', except that the latter will be assembled about
  369. 100 times faster due to the internal structure of the assembler.
  370.  
  371. Note also that TIMES can't be applied to macros: the reason for this
  372. is that TIMES is processed after the macro phase, which allows the
  373. argument to TIMES to contain expressions such as `64-$+buffer' as
  374. above.
  375.  
  376. Effective Addresses
  377. ===================
  378.  
  379. NASM's addressing scheme is very simple, although it can involve
  380. more typing than other assemblers. Where other assemblers
  381. distinguish between a _variable_ (label declared without a colon)
  382. and a _label_ (declared with a colon), and use different means of
  383. addressing the two, NASM is totally consistent.
  384.  
  385. To refer to the contents of a memory location, square brackets are
  386. required. This applies to simple variables, computed offsets,
  387. segment overrides, effective addresses - _everything_. E.g.:
  388.  
  389. wordvar dw 123
  390.     mov ax,[wordvar]
  391.     mov ax,[wordvar+1]
  392.     mov ax,[es:wordvar+bx]
  393.  
  394. NASM does _not_ support the various strange syntaxes used by MASM
  395. and others, such as
  396.  
  397.     mov ax,wordvar    ; this is legal, but means something else
  398.     mov ax,es:wordvar[bx]    ; not even slightly legal
  399.     es mov ax,wordvar[1]    ; the prefix is OK, but not the rest
  400.  
  401. If no square brackets are used, NASM interprets label references to
  402. mean the address of the label. Hence there is no need for MASM's
  403. OFFSET keyword, but
  404.  
  405.     mov ax,wordvar
  406.  
  407. loads AX with the _address_ of the variable `wordvar'.
  408.  
  409. More complicated effective addresses are handled by enclosing them
  410. within square brackets as before:
  411.  
  412.     mov eax,[ebp+2*edi+offset]
  413.     mov ax,[bx+di+8]
  414.  
  415. NASM will cope with some fairly strange effective addresses, if you
  416. try it: provided your effective address expression evaluates
  417. _algebraically_ to something that the instruction set supports, it
  418. will be able to assemble it. For example,
  419.  
  420.     mov eax,[ebx*5]        ; actually assembles to [ebx+ebx*4]
  421.     mov ax,[bx-si+2*si]    ; actually assembles to [bx+si]
  422.  
  423. will both work.
  424.  
  425. There is an ambiguity in the instruction set, which allows two forms
  426. of 32-bit effective address with equivalent meaning:
  427.  
  428.     mov eax,[2*eax+0]
  429.     mov eax,[eax+eax]
  430.  
  431. These two expressions clearly refer to the same address. The
  432. difference is that the first one, if assembled `as is', requires a
  433. four-byte offset to be stored as part of the instruction, so it
  434. takes up more space. NASM will generate the second (smaller) form
  435. for both of the above instructions, in an effort to save space.
  436. There is not, currently, any means for forcing NASM to generate the
  437. larger form of the instruction.
  438.  
  439. An alternative syntax is supported, in which prefixing an operand
  440. with `&' is synonymous with enclosing it in square brackets. The
  441. square bracket syntax is the recommended one, however, and is the
  442. syntax generated by NDISASM. But, for example, `mov eax,&ebx+ecx' is
  443. equivalent to `mov eax,[ebx+ecx]'.
  444.  
  445. Mixing 16 and 32 Bit Code: Unusual Instruction Sizes
  446. ====================================================
  447.  
  448. A number of assemblers seem to have trouble assembling instructions
  449. that use a different operand or address size from the one they are
  450. expecting; as86 is a good example, even though the Linux kernel boot
  451. process (which is assembled using as86) needs several such
  452. instructions and as86 can't do them.
  453.  
  454. Instructions such as `mov eax,2' in 16-bit mode are easy, of course,
  455. and NASM can do them just as well as any other assembler. The
  456. difficult instructions are things like far jumps.
  457.  
  458. Suppose you are in a 16-bit segment, in protected mode, and you want
  459. to execute a far jump to a point in a 32-bit segment. You need to
  460. code a 32-bit far jump in a 16-bit segment; not all assemblers will
  461. easily support this. NASM can, by means of the `word' and `dword'
  462. specifiers. So you can code
  463.  
  464.     jmp 1234h:5678h    ; this uses the default segment size
  465.     jmp word 1234h:5678h    ; this is guaranteed to be 16-bit
  466.     jmp dword 1234h:56789ABCh ; and this is guaranteed 32-bit
  467.  
  468. and NASM will generate correct code for them.
  469.  
  470. Similarly, if you are coding in a 16-bit code segment, but trying to
  471. access memory in a 32-bit data segment, your effective addresses
  472. will want to be 32-bit. Of course as soon as you specify an
  473. effective address containing a 32-bit register, like `[eax]', the
  474. addressing is forced to be 32-bit anyway. But if you try to specify
  475. a simple offset, such as `[label]' or `[0x10000]', you will get the
  476. default address size, which in this case will be wrong. However,
  477. NASM allows you to code `[dword 0x10000]' to force a 32-bit address
  478. size, or conversely `[word wlabel]' to force 16 bits.
  479.  
  480. Be careful not to confuse `word' and `dword' _inside_ the square
  481. brackets with _outside_: consider the instruction
  482.  
  483.     mov word [dword 0x123456],0x7890
  484.  
  485. which moves 16 bits of data to an address specified by a 32-bit
  486. offset. There is no contradiction between the `word' and `dword' in
  487. this instruction, since they modify different aspects of the
  488. functionality. Or, even more confusingly,
  489.  
  490.     call dword far [fs:word 0x4321]
  491.  
  492. which takes an address specified by a 16-bit offset, and extracts a
  493. 48-bit DWORD FAR pointer from it to call.
  494.  
  495. Using this effective-address syntax, the `dword' or `word' override
  496. may come before or after the segment override if any: NASM isn't
  497. fussy. Hence:
  498.  
  499.     mov ax,[fs:dword 0x123456]
  500.     mov ax,[dword fs:0x123456]
  501.  
  502. are equivalent forms, and generate the same code.
  503.  
  504. The LOOP instruction comes in strange sizes, too: in a 16-bit
  505. segment it uses CX as its count register by default, and in a 32-bit
  506. segment it uses ECX. But it's possible to do either one in the other
  507. segment, and NASM will cope by letting you specify the count
  508. register as a second operand:
  509.  
  510.     loop label        ; uses CX or ECX depending on mode
  511.     loop label,cx        ; always uses CX
  512.     loop label,ecx        ; always uses ECX
  513.  
  514. Finally, the string instructions LODSB, STOSB, MOVSB, CMPSB, SCASB,
  515. INSB, and OUTSB can all have strange address sizes: typically, in a
  516. 16-bit segment they read from [DS:SI] and write to [ES:DI], and in a
  517. 32-bit segment they read from [DS:ESI] and write to [ES:EDI].
  518. However, this can be changed by the use of the explicit address-size
  519. prefixes `a16' and `a32'. These prefixes generate null code if used
  520. in the same size segment as they specify, but generate an 0x67
  521. prefix otherwise. Hence `a16' generates no code in a 16-bit segment,
  522. but 0x67 in a 32-bit one, and vice versa. So `a16 lodsb' will always
  523. generate code to read a byte from [DS:SI], no matter what the size
  524. of the segment. There are also explicit operand-size override
  525. prefixes, `o16' and `o32', which will optionally generate 0x66
  526. bytes, but these are provided for completeness and should never have
  527. to be used. (Note that NASM does not support the LODS, STOS, MOVS
  528. etc. forms of the string instructions.)
  529.  
  530. Constants
  531. =========
  532.  
  533. NASM can accept three kinds of constant: _numeric_, _character_ and
  534. _string_ constants.
  535.  
  536. Numeric constants are simply numbers. NASM supports a variety of
  537. syntaxes for expressing numbers in strange bases: you can do any of
  538.  
  539.     100    ; this is decimal
  540.     0x100    ; hex
  541.     100h    ; hex as well
  542.     $100    ; hex again
  543.     100q    ; octal
  544.     100b    ; binary
  545.  
  546. NASM does not support A86's syntax of treating anything with a
  547. leading zero as hex, nor does it support the C syntax of treating
  548. anything with a leading zero as octal. Leading zeros make no
  549. difference to NASM. (Except that, as usual, if you have a hex
  550. constant beginning with a letter, and you want to use the trailing-H
  551. syntax to represent it, you have to use a leading zero so that NASM
  552. will recognise it as a number instead of a label.)
  553.  
  554. The `x' in `0x100', and the trailing `h', `q' and `b', may all be
  555. upper case if you want.
  556.  
  557. Character constants consist of up to four characters enclosed in
  558. single or double quotes. No escape character is defined for
  559. including the quote character itself: if you want to declare a
  560. character constant containing a double quote, enclose it in single
  561. quotes, and vice versa.
  562.  
  563. Character constants' values are worked out in terms of a
  564. little-endian computer: if you code
  565.  
  566.     mov eax,'abcd'
  567.  
  568. then if you were to examine the binary output from NASM, it would
  569. contain the visible string `abcd', which of course means that the
  570. actual value loaded into EAX would be 0x64636261, not 0x61626364.
  571.  
  572. String constants are like character constants, only more so: if a
  573. character constant appearing as operand to a DB, DW or DD is longer
  574. than the word size involved (1, 2 or 4 respectively), it will be
  575. treated as a string constant instead, which is to say the
  576. concatenation of separate character constants.
  577.  
  578. For example,
  579.  
  580.     db 'hello, world'
  581.  
  582. declares a twelve-character string constant. And
  583.  
  584.     dd 'dontpanic'
  585.  
  586. (a string constant) is equivalent to writing
  587.  
  588.     dd 'dont','pani','c'
  589.  
  590. (three character constants), so that what actually gets assembled is
  591. equivalent to
  592.  
  593.     db 'dontpanic',0,0,0
  594.  
  595. (It's worth noting that one of the reasons for the reversal of
  596. character constants is so that the instruction `dw "ab"' has the
  597. same meaning whether "ab" is treated as a character constant or a
  598. string constant. Hence there is less confusion.)
  599.  
  600. Expressions
  601. ===========
  602.  
  603. Expressions in NASM can be formed of the following operators: `|'
  604. (bitwise OR), `^' (bitwise XOR), `&' (bitwise AND), `<<' and `>>'
  605. (logical bit shifts), `+', `-', `*' (ordinary addition, subtraction
  606. and multiplication), `/', `%' (unsigned division and modulo), `//',
  607. `%%' (signed division and modulo), `~' (bitwise NOT), and the
  608. operators SEG and WRT (see `SEG and WRT' below).
  609.  
  610. The order of precedence is:
  611.  
  612. |            lowest
  613. ^
  614. &
  615. << >>
  616. binary + and -
  617. * / % // %%
  618. unary + and -, ~, SEG    highest
  619.  
  620. As usual, operators within a precedence level associate to the left
  621. (i.e. `2-3-4' evaluates the same way as `(2-3)-4').
  622.  
  623. Note that since the `%' character is used by the preprocessor, it's
  624. worth making sure that the `%' and `%%' operators are followed by a
  625. space, to prevent the preprocessor trying to interpret them as
  626. macro-related things.
  627.  
  628. A form of algebra is done by NASM when evaluating expressions: I
  629. have already stated that an effective address expression such as
  630. `[EAX*6-EAX]' will be recognised by NASM as algebraically equivalent
  631. to `[EAX*4+EAX]', and assembled as such. In addition, algebra can be
  632. done on labels as well: `label2*2-label1' is an acceptable way to
  633. define an address as far beyond `label2' as `label1' is before it.
  634. (In less algebraically capable assemblers, one might have to write
  635. that as `label2 + (label2-label1)', where the value of every
  636. sub-expression is either a valid address or a constant. NASM can of
  637. course cope with that version as well.)
  638.  
  639. Expressions may also contain the special token `$', known as a Here
  640. token, which always evaluates to the address of the current assembly
  641. point. (That is, the address of the assembly point _before_ the
  642. current instruction gets assembled.) The special token `$$'
  643. evaluates to the address of the beginning of the current section;
  644. this can be used for alignment, as shown below:
  645.  
  646.     times ($$-$) & 3 nop    ; pad with NOPs to 4-byte boundary
  647.  
  648. Note that this technique aligns to a four-byte boundary with respect
  649. to the beginning of the _segment_; if you can't guarantee that the
  650. segment itself begins on a four-byte boundary, this alignment is
  651. useless or worse. Be sure you know what kind of alignment you can
  652. guarantee to get out of your linker before you start trying to use
  653. TIMES to align to page boundaries. (Of course, the `obj' and `os2'
  654. file formats can happily cope with page alignment, provided you
  655. specify that segment attribute.)
  656.  
  657. SEG and WRT
  658. ===========
  659.  
  660. NASM contains the capability for its object file formats (currently,
  661. only `obj' and its variant `os2' make use of this) to permit
  662. programs to directly refer to the segment-base values of their
  663. segments. This is achieved either by the object format defining the
  664. segment names as symbols (`obj' and `os2' do this), or by the use of
  665. the SEG operator.
  666.  
  667. SEG is a unary prefix operator which, when applied to a symbol
  668. defined in a segment, will yield the segment base value of that
  669. segment. (In `obj' and `os2' format, symbols defined in segments
  670. which are grouped are considered to be primarily a member of the
  671. _group_, not the segment, and the return value of SEG reflects
  672. this.)
  673.  
  674. SEG may be used for far pointers: it is guaranteed that for any
  675. symbol `sym', using the offset `sym' from the segment base `SEG sym'
  676. yields a correct pointer to the symbol. Hence you can code a far
  677. call by means of
  678.  
  679.     CALL SEG routine:routine
  680.  
  681. or store a far pointer in a data segment by
  682.  
  683.     DW routine, SEG routine
  684.  
  685. For convenience, NASM supports the forms
  686.  
  687.     CALL FAR routine
  688.     JMP FAR routine
  689.  
  690. as direct synonyms for the canonical syntax
  691.  
  692.     CALL SEG routine:routine
  693.     JMP SEG routine:routine
  694.  
  695. No alternative syntax for
  696.  
  697.     DW routine, SEG routine
  698.  
  699. is supported.
  700.  
  701. Simply referring to `sym', for some symbol, will return the offset
  702. of `sym' from its _preferred_ segment base (as returned from `SEG
  703. sym'); sometimes, you may want to obtain the offset of `sym' from
  704. some _other_ segment base. (E.g. the offset of `sym' from the base
  705. of the segment it's in, where normally you'd get the offset from a
  706. group base). This is accomplished using the WRT (With Reference To)
  707. keyword: if `sym' is defined in segment `seg' but you want its
  708. offset relative to the beginning of segment `seg2', you can do
  709.  
  710.     mov ax,sym WRT seg2
  711.  
  712. The right-hand operand to WRT must be a segment-base value. You can
  713. also do `sym WRT SEG sym2' if you need to.
  714.  
  715. Critical Expressions
  716. ====================
  717.  
  718. NASM is a two-pass assembler: it goes over the input once to
  719. determine the location of all the symbols, then once more to
  720. actually generate the output code. Most expressions are
  721. non-critical, in that if they contain a forward reference and hence
  722. their correct value is unknown during the first pass, it doesn't
  723. matter. However, arguments to RESB, RESW and RESD, and the argument
  724. to the TIMES prefix, can actually affect the _size_ of the generated
  725. code, and so it is critical that the expression can be evaluated
  726. correctly on the first pass. So in these situations, expressions may
  727. not contain forward references. This prevents NASM from having to
  728. sort out a mess such as
  729.  
  730.     times (label-$) db 0
  731. label:    db 'where am I?'
  732.  
  733. in which the TIMES argument could equally legally evaluate to
  734. _anything_, or perhaps even worse,
  735.  
  736.     times (label-$+1) db 0
  737. label:    db 'NOW where am I?'
  738.  
  739. in which any value for the TIMES argument is by definition invalid.
  740.  
  741. Since NASM is a two-pass assembler, this criticality condition also
  742. applies to the argument to EQU. Suppose, if this were not the case,
  743. we were to have the setup
  744.  
  745.   mov ax,a
  746. a equ b
  747. b:
  748.  
  749. On pass one, `a' cannot be defined properly, since `b' is not known
  750. yet. On pass two, `b' is known, so line two can define `a' properly.
  751. Unfortunately, line 1 needed `a' to be defined properly, so this
  752. code will not assemble using only two passes.
  753.  
  754. There's a related issue: in an effective address such as
  755. `[eax+offset]', the value of `offset' can be stored as either 1 or 4
  756. bytes. NASM will use the one-byte form if it knows it can, to save
  757. space, but will therefore be fooled by the following:
  758.  
  759.   mov eax,[ebx+offset]
  760. offset equ 10
  761.  
  762. In this case, although `offset' is a small value and could easily
  763. fit into the one-byte form of the instruction, when NASM sees the
  764. instruction in the first pass it doesn't know what `offset' is, and
  765. for all it knows `offset' could be a symbol requiring relocation. So
  766. it will allocate the full four bytes for the value of `offset'. This
  767. can be solved by defining `offset' before it's used.
  768.  
  769. Local Labels
  770. ============
  771.  
  772. NASM takes its local label scheme mainly from the old Amiga
  773. assembler Devpac: a local label is one that begins with a period.
  774. The `localness' comes from the fact that local labels are associated
  775. with the previous non-local label, so that you may declare the same
  776. local label twice if a non-local one intervenes. Hence:
  777.  
  778. label1    ; some code
  779. .loop    ; some more code
  780.     jne .loop
  781.     ret
  782. label2    ; some code
  783. .loop    ; some more code
  784.     jne .loop
  785.     ret
  786.  
  787. In the above code, each `jne' instruction jumps to the line of code
  788. before it, since the `.loop' labels are distinct from each other.
  789.  
  790. NASM, however, introduces an extra capability not present in Devpac,
  791. which is that the local labels are actually _defined_ in terms of
  792. their associated non-local label. So if you really have to, you can
  793. write
  794.  
  795. label3    ; some more code
  796.     ; and some more
  797.     jmp label1.loop
  798.  
  799. So although local labels are _usually_ local, it is possible to
  800. reference them from anywhere in your program, if you really have to.
  801.  
  802. Assembler Directives
  803. ====================
  804.  
  805. Assembler directives appear on a line by themselves (apart from a
  806. comment). They come in two forms: user-level directives and
  807. primitive directives. Primitive directives are enclosed in square
  808. brackets (no white space may appear before the opening square
  809. bracket, although white space and a comment may come after the
  810. closing bracket), and were the only form of directive supported by
  811. earlier versions of NASM. User-level directives look the same, only
  812. without the square brackets, and are the more modern form. (They are
  813. implemented as macros expanding to primitive directives.) There is a
  814. distinction in functionality, which is explained below in the
  815. section on structures.
  816.  
  817. Some directives are universal: they may be used in any situation,
  818. and do not change their syntax. The universal directives are listed
  819. below.
  820.  
  821. `BITS 16' or `BITS 32' switches NASM into 16-bit or 32-bit mode.
  822. (This is equivalent to USE16 and USE32 segments, in TASM or MASM.)
  823. In 32-bit mode, instructions are prefixed with 0x66 or 0x67 prefixes
  824. when they use 16-bit data or addresses; in 16-bit mode, the reverse
  825. happens. NASM's default depends on the object format; the defaults
  826. are documented with the formats. (See `obj' and `os2', in
  827. particular, for some unusual behaviour.)
  828.  
  829. `SECTION name' or `SEGMENT name' changes which section the code you
  830. write will be assembled into. Acceptable section names vary between
  831. output formats, but most formats (indeed, all formats at the moment)
  832. support the names `.text', `.data' and `.bss'. Note that `.bss' is
  833. an uninitialised data section, and so you will receive a warning
  834. from NASM if you try to assemble any code or data in it. The only
  835. thing you can do in `.bss' without triggering a warning is to use
  836. RESB, RESW and RESD. That's what they're for.
  837.  
  838. `ABSOLUTE address' can be considered a different form of `SECTION',
  839. in that it must be overridden using a SECTION directive once you
  840. have finished using it. It is used to assemble notional code at an
  841. absolute offset address; of course, you can't actually assemble
  842. _code_ there, since no object file format is capable of putting the
  843. code in place, but you can use RESB, RESW and RESD, and you can
  844. define labels. Hence you could, for example, define a C-like data
  845. structure by means of
  846.  
  847.             absolute 0
  848.     stLong  resd 1
  849.     stWord  resw 1
  850.     stByte1 resb 1
  851.     stByte2 resb 1
  852.     st_size:
  853.             segment .text
  854.  
  855. and then carry on coding. This defines `stLong' to be zero, `stWord'
  856. to be 4, `stByte1' to be 6, `stByte2' to be 7 and `st_size' to be 8.
  857. So this has defined a data structure. The STRUC directive provides a
  858. nicer way to do this: see below.
  859.  
  860. `EXTERN symbol' defines a symbol as being `external', in the C
  861. sense: `EXTERN' states that the symbol is _not_ declared in this
  862. module, but is declared elsewhere, and that you wish to _reference_
  863. it in this module.
  864.  
  865. `GLOBAL symbol' defines a symbol as being global, in the sense that
  866. it is exported from this module and other modules may reference it.
  867. All symbols are local, unless declared as global. Note that the
  868. `GLOBAL' directive must appear before the definition of the symbol
  869. it refers to.
  870.  
  871. `COMMON symbol size' defines a symbol as being common: it is
  872. declared to have the given size, and it is merged at link time with
  873. any declarations of the same symbol in other modules. This is not
  874. _fully_ supported in the `obj' or `os2' file format: see the section
  875. on `obj' for details.
  876.  
  877. `STRUC structure' begins the definition of a data structure, and
  878. `ENDSTRUC' ends it. The structure shown above may be defined,
  879. exactly equivalently, using STRUC as follows:
  880.  
  881.             struc st
  882.     stLong  resd 1
  883.     stWord  resw 1
  884.     stByte  resb 1
  885.     stStr   resb 32
  886.             endstruc
  887.  
  888. Notice that this code still defines the symbol `st_size' to be the
  889. size of the structure. The `_size' suffix is automatically appended
  890. to the structure name. Notice also that the assembler takes care of
  891. remembering which section you were assembling in (whereas in the
  892. version using `ABSOLUTE' it was up to the programmer to sort that
  893. out).
  894.  
  895. `ISTRUC structure' begins the declaration of an initialised instance
  896. of a data structure. You can then use the `AT' macro to assign
  897. values to the structure members, and `IEND' to finish. So, for
  898. example, given the structure `st' above:
  899.  
  900.         istruc st
  901.         at stLong, dd 0x1234
  902.         at stWord, dw 23
  903.         at stByte, db 'q'
  904.         at stStr, db 'hello, world', 13, 10, 0
  905.         iend
  906.  
  907. Note that there's nothing stopping the instruction after `at' from
  908. overflowing on to the next line if you want. So the above example
  909. could just as well have contained
  910.  
  911.         at stStr, db 'hello, world'
  912.         db 13, 10, 0
  913.  
  914. or even (if you prefer this style)
  915.  
  916.         at stStr
  917.         db 'hello, world'
  918.         db 13, 10, 0
  919.  
  920. Note also that the `ISTRUC' mechanism is implemented as a set of
  921. macros, and uses TIMES internally to achieve its effect; so the
  922. structure fields must be initialised in the same order as they were
  923. defined in.
  924.  
  925. This is where user-level directives differ from primitives: the
  926. `SECTION' (and `SEGMENT') user-level directives don't just call the
  927. primitive versions, but they also `%define' the special preprocessor
  928. symbol `__SECT__' to be the primitive directive that specifies the
  929. current section. So the `ENDSTRUC' directive can remember what
  930. section the assembly was directed to before the structure definition
  931. began. For this reason, there is no primitive version of STRUC or
  932. ENDSTRUC - they are implemented in terms of ABSOLUTE and SECTION.
  933. This also means that if you use STRUC before explicitly announcing a
  934. target section, you should explicitly announce one after ENDSTRUC.
  935.  
  936. Directives may also be specific to the output file format. At
  937. present, the `bin', `obj' and `os2' formats define extra directives,
  938. which are specified below.
  939.  
  940. The Preprocessor
  941. ================
  942.  
  943. NASM contains a full-featured macro preprocessor, which supports
  944. conditional assembly, multi-level file inclusion, two forms of macro
  945. (single-line and multi-line), and a `context stack' mechanism for
  946. extra macro power. Preprocessor directives all begin with a `%'
  947. sign.
  948.  
  949. Single-line macros
  950. ------------------
  951.  
  952. Single-line macros are defined in a similar way to C, using the
  953. `%define' command. Hence you can do:
  954.  
  955.    %define ctrl 0x1F &
  956.    %define param(a,b) ((a)+(a)*(b))
  957.      mov byte [param(2,ebx)], ctrl 'D'
  958.  
  959. which will expand to
  960.  
  961.      mov byte [(2)+(2)*(ebx)], 0x1F & 'D'
  962.  
  963. When the expansion of a single-line macro contains tokens which
  964. invoke another macro, the expansion is performed at invocation time,
  965. not at definition time. Thus the code
  966.  
  967.    %define a(x) 1+b(x)
  968.    %define b(x) 2*x
  969.      mov ax,a(8)
  970.  
  971. will evaluate in the expected way to `mov ax,1+2*8', even though the
  972. macro `b' wasn't defined at the time of definition of `a'.
  973.  
  974. Macros defined with `%define' are case sensitive: after `%define foo
  975. bar', only `foo' will expand to bar: `Foo' or `FOO' will not. By
  976. using `%idefine' instead of `%define' (the `i' stands for
  977. `insensitive') you can define all the case variants of a macro at
  978. once, so that `%idefine foo bar' would cause `foo', `Foo' and `FOO'
  979. all to expand to `bar'.
  980.  
  981. There is a mechanism which detects when a macro call has occurred as
  982. a result of a previous expansion of the same macro, to guard against
  983. circular references and infinite loops. If this happens, the
  984. preprocessor will only expand the first occurrence of the macro.
  985. Hence:
  986.  
  987.    %define a(x) 1+a(x)
  988.      mov ax,a(3)        ; becomes 1+a(3) and expands no further
  989.  
  990. This can be useful for doing things like this:
  991.  
  992.    %macro extrn 1       ; see next section for explanation of `%macro'
  993.      extern _%1
  994.      %define %1 _%1
  995.    %endmacro
  996.  
  997. which would avoid having to put leading underscores on external
  998. variables, because you could just code
  999.  
  1000.      extrn foo
  1001.      mov ax,foo
  1002.  
  1003. and it would expand as
  1004.  
  1005.      extern foo
  1006.    %define foo _foo
  1007.      mov ax,foo         ; becomes mov ax,_foo as required
  1008.  
  1009. Single-line macros with parameters can be overloaded: it is possible
  1010. to define two or more single-line macros with the same name, each
  1011. taking a different number of parameters, and the macro processor
  1012. will be able to distinguish between them. However, a parameterless
  1013. single-line macro excludes the possibility of any macro of the same
  1014. name _with_ parameters, and vice versa (though single-line macros
  1015. may be redefined, keeping the same number of parameters, without
  1016. error).
  1017.  
  1018. You can pre-define single-line macros using the `-d' option on the
  1019. NASM command line, such as
  1020.  
  1021.     nasm filename -dDEBUG
  1022.  
  1023. (and then you might have various conditional-assembly bits under
  1024. `%ifdef DEBUG'), or possibly
  1025.  
  1026.     nasm filename -dTYPE=4
  1027.  
  1028. (which might allow you to re-assemble your code to do several
  1029. different things depending on the value of TYPE).
  1030.  
  1031. Multiple-line macros
  1032. --------------------
  1033.  
  1034. These are defined using `%macro' and `%endmacro', so that simple things
  1035. like this can be done:
  1036.  
  1037.    %macro prologue 0
  1038.      push ebp
  1039.      mov ebp,esp
  1040.    %endmacro
  1041.  
  1042. This defines `prologue' to be a multi-line macro, taking no
  1043. parameters, which expands to the two lines of code given.
  1044.  
  1045. Similarly to single-line macros, multi-line macros are case-
  1046. sensitive, unless you define them using `%imacro' instead of
  1047. `%macro'.
  1048.  
  1049. The `0' on the `%macro' line indicates that the macro `prologue'
  1050. expects no parameters. Macros can be overloaded: if two macros are
  1051. defined with the same name but different numbers of parameters, they
  1052. will be treated as separate. Multi-line macros may not be redefined.
  1053.  
  1054. The assembler will usually generate a warning if you code a line
  1055. which looks like a macro call but involves a number of parameters
  1056. which the macro in question isn't ready to support. (For example, if
  1057. you code a macro `%macro foo 1' and also `%macro foo 3', then you
  1058. write `foo a,b', a warning will be generated.) This feature can be
  1059. disabled by the use of the command line option `-w-macro-params',
  1060. since sometimes it's intentional (for example, you might define
  1061. `%macro push 2' to allow you to push two registers at once; but
  1062. `push ax' shouldn't then generate a warning).
  1063.  
  1064. Macros taking parameters can be written using `%1', `%2' and so on
  1065. to reference the parameters. So this code
  1066.  
  1067.    %macro movs 2
  1068.      push %2
  1069.      pop %1
  1070.    %endmacro
  1071.      movs ds,cs
  1072.  
  1073. will define a macro `movs' to perform an effective MOV operation
  1074. from segment to segment register. The macro call given would of
  1075. course expand to `push cs' followed by `pop ds'.
  1076.  
  1077. You can define a label inside a macro in such a way as to make it
  1078. unique to that macro call (so that repeated calls to the same macro
  1079. won't produce multiple labels with the same name), by prefixing it
  1080. with `%%'. So:
  1081.  
  1082.    %macro retz
  1083.      jnz %%skip
  1084.      ret
  1085.    %%skip:
  1086.    %endmacro
  1087.  
  1088. This defines a different label in place of `%%skip' every time it's
  1089. called. (Of course the above code could have easily been coded using
  1090. `jnz $+3', but not in more complex cases...) The actual label
  1091. defined would be `..@2345.skip', where 2345 is replaced by some
  1092. number that changes with each macro call. Users are warned to avoid
  1093. defining labels of this shape themselves.
  1094.  
  1095. Sometimes you want a macro to be able to accept arbitrarily many
  1096. parameters and lump them into one. This can be done using the `+'
  1097. modifier on the `%macro' line:
  1098.  
  1099.    %macro fputs 2+
  1100.    [section .data] ; this is done as a primitive to avoid
  1101.                    ; disturbing the __SECT__ define
  1102.    %%str db %2
  1103.    %%end:
  1104.    __SECT__        ; this expands to a whole [section xxx] primitive
  1105.      mov dx,%%str
  1106.      mov cx,%%end-%%str
  1107.      mov bx,%1
  1108.      call writefile
  1109.    %endmacro
  1110.      fputs [filehandle], "hi there", 13, 10
  1111.  
  1112. This declares `fputs' to be a macro that accepts _at least two_
  1113. parameters, and all parameters after the first one are lumped
  1114. together as part of the last specified one (in this case %2). So in
  1115. the macro call, `%1' expands to `[filehandle]' while `%2' expands to
  1116. the whole remainder of the line: `"hi there", 13, 10'. Note also the
  1117. switching of sections in the middle of this macro expansion, to
  1118. ensure separation of data and code.
  1119.  
  1120. There is an alternative mechanism for putting commas in macro
  1121. parameters: instead of specifying the large-parameter-ness at macro
  1122. definition time, you can specify it at macro call time, by the use
  1123. of braces to surround a parameter which you want to contain commas.
  1124. So:
  1125.  
  1126.    %macro table_entry 2
  1127.    %%start:
  1128.      db %1
  1129.      times 32-($-%%start) db 0
  1130.      db %2
  1131.      times 64-($-%%start) db 0
  1132.    %endmacro
  1133.      table_entry 'foo','bar'
  1134.      table_entry 'megafoo', { 27,'[1mBAR!',27,'[m' }
  1135.  
  1136. will expand to, effectively (actually, there will be labels present,
  1137. but these have been omitted for clarity), the following:
  1138.  
  1139.      db 'foo'
  1140.      times 32-3 db 0
  1141.      db 'bar'
  1142.      times 64-35 db 0
  1143.      db 'megafoo'
  1144.      times 32-7 db 0
  1145.      db 27,'[1mBAR!',27,'[m'
  1146.      times 64-46 db 0
  1147.  
  1148. Macro parameter expansions can be concatenated on to other tokens,
  1149. so that you can do this:
  1150.  
  1151.    %macro keytab_entry 2
  1152.    keypos%1 equ $-keytab
  1153.      db %2
  1154.    %endmacro
  1155.    keytab:
  1156.      keytab_entry F1,128+1
  1157.      keytab_entry F2,128+2
  1158.      keytab_entry Return,13
  1159.  
  1160. which will define labels called `keyposF1', `keyposF2' and
  1161. `keyposReturn'. You can similarly do concatenations on the other
  1162. end, such as `%1foo'. If you need to concatenate a digit on to the
  1163. end of a macro parameter expansion, you can do this by enclosing the
  1164. parameter number in braces: `%{1}' is always a valid synonym for
  1165. `%1', and has the advantage that it can be legitimately prepended to
  1166. a digit, as in `%{1}2', and cause no confusion with `%{12}'.
  1167. Macro-specific labels and defines can be concatenated similarly:
  1168. `%{%foo}bar' will succeed where `%%foobar' would cause confusion.
  1169. (As it happens, `%%foobar' would work anyway, due to the format of
  1170. macro-specific labels, but for clarity, `%{%foo}bar' is recommended
  1171. if you _really_ want to do anything this perverse...)
  1172.  
  1173. The parameter handling has a special case: it can treat a macro
  1174. parameter specially if it's thought to contain a condition code. The
  1175. reference `%+1' is identical to `%1' except that it will perform an
  1176. initial sanity check to see if the parameter in question is a
  1177. condition code; more usefully, the reference `%-1' will produce the
  1178. _opposite_ condition code to the one specified in the parameter.
  1179. This allows for things such as a conditional-MOV macro to be
  1180. defined:
  1181.  
  1182.    %macro movc 3
  1183.      j%-1 %%skip
  1184.      mov %2,%3
  1185.    %%skip:
  1186.    %endmacro
  1187.      movc ae,ax,bx
  1188.  
  1189. which will expand to something like
  1190.  
  1191.      jnae ..@1234.skip
  1192.      mov ax,bx
  1193.    ..@1234.skip:
  1194.  
  1195. Note that `%+1' will allow CXZ or ECXZ to be passed as condition
  1196. codes, but `%-1' will of course be unable to invert them.
  1197.  
  1198. Parameters can also be defaulted: you can define a macro which, for
  1199. example, said
  1200.  
  1201.    %macro strange 1-3 bx,3
  1202.      < some expansion text >
  1203.    %endmacro
  1204.  
  1205. This macro takes between 1 and 3 parameters (inclusive); if
  1206. parameter 2 is not specified it defaults to BX, and if parameter 3
  1207. is not specified it defaults to 3. So the calls
  1208.  
  1209.      strange dx,si,di
  1210.      strange dx,si
  1211.      strange dx
  1212.  
  1213. would be equivalent to
  1214.  
  1215.      strange dx,si,di
  1216.      strange dx,si,3
  1217.      strange dx,bx,3
  1218.  
  1219. Defaults may be omitted, in which case they are taken to be blank.
  1220.  
  1221. `%endm' is a valid synonym for `%endmacro'.
  1222.  
  1223. The specification for the number of macro parameters can be suffixed
  1224. with `.nolist' if you don't want the macro to be explicitly expanded
  1225. in listing files:
  1226.  
  1227.    %macro ping 1-2+.nolist
  1228.      ; some stuff
  1229.    %endmacro
  1230.  
  1231. Standard Macros and `%clear'
  1232. ----------------------------
  1233.  
  1234. NASM defines a set of standard macros, before the input file gets
  1235. processed; these are primarily there in order to provide standard
  1236. language features (such as structure support). However, it's
  1237. conceivable that a user might want to write code that doesn't have
  1238. the standard macros defined; you can achieve this by using the
  1239. preprocessor directive `%clear' at the top of your program, which
  1240. will undefine _everything_ that's defined by the preprocessor.
  1241.  
  1242. In particular, NASM defines the symbols `__NASM_MAJOR__' and
  1243. `__NASM_MINOR__' to be the major and minor version numbers of NASM.
  1244.  
  1245. Conditional Assembly
  1246. --------------------
  1247.  
  1248. Similarly to the C preprocessor, the commands `%ifdef' and `%endif'
  1249. may be used to bracket a section of code, which will then only be
  1250. assembled if at least one of the identifiers following `%ifdef' is
  1251. defined as a single-line macro. The command `%ifndef' has opposite
  1252. sense to `%ifdef', and `%else' can be placed between the `%if' and
  1253. the `%endif' to work as expected. Since there is no analogue to C's
  1254. `#if', there is no precise `elif' directive, but `%elifdef' and
  1255. `%elifndef' work as expected.
  1256.  
  1257. There is another family of `%if' constructs: `%ifctx', `%ifnctx',
  1258. `%elifctx' and `%elifnctx', which operate on the context stack
  1259. (described below).
  1260.  
  1261. File Inclusion
  1262. --------------
  1263.  
  1264. You can include a file using the `%include' directive. Included
  1265. files are searched for in the current directory, and then in all
  1266. directories specified on the command line with the `-i' option.
  1267. (Note that the directories specified on the command line are
  1268. directly prepended to the filename, so they must include the
  1269. necessary trailing slash under DOS or Unix, or the equivalent on
  1270. other systems.)
  1271.  
  1272. This, again, works like C: `%include' is used to include a file. Of
  1273. course it's quite likely you'd want to do the normal sort of thing
  1274. inside the file:
  1275.  
  1276.    %ifndef MY_MACROS_FILE
  1277.    %define MY_MACROS_FILE
  1278.      < go and define some macros >
  1279.    %endif
  1280.  
  1281. and then elsewhere
  1282.  
  1283.    %include "my-macros-file"
  1284.      < some code making use of the macros >
  1285.  
  1286. so that it doesn't matter if the file accidentally gets included
  1287. more than once.
  1288.  
  1289. You can force an include file to be included without using a
  1290. `%include' command, by specifying it as a pre-include file on the
  1291. command line using the `-p' option.
  1292.  
  1293. The Context Stack
  1294. -----------------
  1295.  
  1296. This is a feature which adds a whole extra level of power to NASM's
  1297. macro capability. The context stack is an internal object within the
  1298. preprocessor, which holds a stack of `contexts'. Each context has a
  1299. name - just an identifier-type token - and can also have labels and
  1300. `%define' macros associated with it. Other macros can manipulate the
  1301. context stack: this is where the power comes in.
  1302.  
  1303. To start with: the preprocessor command `%push' will create a new
  1304. context with the given name, and push it on to the top of the stack.
  1305. `%pop', taking no arguments, pops the top context off the stack and
  1306. destroys it. `%repl' renames the top context without destroying any
  1307. associated labels or macros, so it's distinct from doing `%pop'
  1308. followed by `%push'. Finally, `%ifctx' and `%ifnctx' invoke
  1309. conditional assembly based on the name of the top context. (The
  1310. alternative forms `%elifctx' and `%elifnctx' are also available.)
  1311.  
  1312. As well as the `%%foo' syntax to define labels specific to a macro
  1313. call, there is also the syntax `%$foo' to define a label specific to
  1314. the context currently on top of the stack. `%$$foo' can be used to
  1315. refer to the context below that, or `%$$$foo' below that, and so on.
  1316.  
  1317. This lot allows the definition of macro combinations that enclose
  1318. other code, such as the following big example:
  1319.  
  1320.    %macro if 1
  1321.      %push if
  1322.      j%-1 %$ifnot
  1323.    %endmacro
  1324.    %macro else 0
  1325.      %ifctx if
  1326.        %repl else
  1327.        jmp %$ifend
  1328.        %$ifnot:
  1329.      %else
  1330.        %error "expected `if' before `else'"
  1331.      %endif
  1332.    %endmacro
  1333.    %macro endif 0
  1334.      %ifctx if
  1335.        %$ifnot:
  1336.        %pop
  1337.      %elifctx else
  1338.        %$ifend:
  1339.        %pop
  1340.      %else
  1341.        %error "expected `if' or `else' before `endif'"
  1342.      %endif
  1343.    %endmacro
  1344.  
  1345. This will cope with a large `if/endif' construct _or_ an
  1346. `if/else/endif', without flinching. So you can code:
  1347.  
  1348.      cmp ax,bx
  1349.      if ae
  1350.        cmp bx,cx
  1351.        if ae
  1352.          mov ax,cx
  1353.        else
  1354.          mov ax,bx
  1355.        endif
  1356.      else
  1357.        cmp ax,cx
  1358.        if ae
  1359.          mov ax,cx
  1360.        endif
  1361.      endif
  1362.  
  1363. which will place the smallest out of AX, BX and CX into AX. Note the
  1364. use of `%repl' to change the current context from `if' to `else'
  1365. without disturbing the associated labels `%$ifend' and `%$ifnot';
  1366. also note that the stack mechanism allows handling of nested IF
  1367. statements without a hitch, and that conditional assembly is used in
  1368. the `endif' macro in order to cope with the two possible forms with
  1369. and without an `else'. Note also the directive `%error', which
  1370. allows the user to report errors on improper invocation of a macro
  1371. and so can catch unmatched `endif's at preprocess time.
  1372.  
  1373. Output Formats
  1374. ==============
  1375.  
  1376. The current output formats supported are `bin', `aout', `coff',
  1377. `elf', `as86', `obj', `os2', `win32', `rdf', and the debug
  1378. pseudo-format `dbg'.
  1379.  
  1380. `bin': flat-form binary
  1381. -----------------------
  1382.  
  1383. This is at present the only output format that generates instantly
  1384. runnable code: all the others produce object files that need linking
  1385. before they become executable.
  1386.  
  1387. `bin' output files contain no red tape at all: they simply contain
  1388. the binary representation of the exact code you wrote.
  1389.  
  1390. The `bin' format supports a format-specific directive, which is ORG.
  1391. `ORG addr' declares that your code should be assembled as if it were
  1392. to be loaded into memory at the address `addr'. So a DOS .COM file
  1393. should state `ORG 0x100', and a DOS .SYS file should state `ORG 0'.
  1394. There should be _one_ ORG directive, at most, in an assembly file:
  1395. NASM does not support the use of ORG to jump around inside an object
  1396. file, like MASM does (see the `Bugs' section for a demonstration of
  1397. the use of MASM's form of ORG to do something that NASM's won't do.)
  1398.  
  1399. Like almost all formats (but not `obj' or `os2'), the `bin' format
  1400. defines the section names `.text', `.data' and `.bss'. The layout is
  1401. that `.text' comes first in the output file, followed by `.data',
  1402. and notionally followed by `.bss'. So if you declare a BSS section
  1403. in a flat binary file, references to the BSS section will refer to
  1404. space past the end of the actual file. The `.data' and `.bss'
  1405. sections are considered to be aligned on four-byte boundaries: this
  1406. is achieved by inserting padding zero bytes between the end of the
  1407. text section and the start of the data, if there is data present. Of
  1408. course if no SECTION directives are present, everything will go into
  1409. `.text', and you will get nothing in the output except the code you
  1410. wrote.
  1411.  
  1412. `bin' silently ignores GLOBAL directives, and will also not complain
  1413. at EXTERN ones. You only get an error if you actually _reference_ an
  1414. external symbol.
  1415.  
  1416. Using the `bin' format, the default output filename is `filename'
  1417. for inputs of `filename.asm'. If there is no extension to be
  1418. removed, output will be placed in `nasm.out' and a warning will be
  1419. generated.
  1420.  
  1421. `bin' defaults to 16-bit assembly mode.
  1422.  
  1423. `aout' and `elf': Linux object files
  1424. ------------------------------------
  1425.  
  1426. These two object formats are the ones used under Linux. They have no
  1427. format-specific directives, and their default output filename is
  1428. `filename.o'.
  1429.  
  1430. `aout' defines the three standard sections `.text', `.data' and
  1431. `.bss'. `elf' also, defines these three, but in addition it can
  1432. support user-defined section names, which can be declared along with
  1433. section attributes like this:
  1434.  
  1435.     section foo align=32 exec
  1436.     section bar write nobits
  1437.  
  1438. The available options are:
  1439.  
  1440. - A section can be `progbits' (the default) or `nobits'. `nobits'
  1441.   sections are BSS: their contents are not stored in the object
  1442.   file, and the only thing you can sensibly do in one is RESB.
  1443.   `progbits' are normal sections.
  1444.  
  1445. - A section can be `exec' (indicating that it contains executable
  1446.   code), or `noexec' (the default).
  1447.  
  1448. - A section can be `write' (indicating that it should be writable
  1449.   when linked), or `nowrite' (the default).
  1450.  
  1451. - A section can be `alloc' (indicating that its contents should be
  1452.   loaded into program VM at load time; the default) or `noalloc'
  1453.   (for storing comments and things that don't form part of the
  1454.   loaded program).
  1455.  
  1456. - You can specify a power of two for the section alignment by
  1457.   writing `align=64' or similar.
  1458.  
  1459. The attributes of the default sections `.text', `.data' and `.bss'
  1460. can also be redefined from their defaults. The NASM defaults are:
  1461.  
  1462. section .text align=16 alloc exec nowrite progbits
  1463. section .data align=4 alloc write noexec progbits
  1464. section .bss align=4 alloc write noexec nobits
  1465.  
  1466. ELF is a much more featureful object-file format than a.out: in
  1467. particular it has enough features to support the writing of position
  1468. independent code by means of a global offset table, and position
  1469. independent shared libraries by means of a procedure linkage table.
  1470. Unfortunately NASM, as yet, does not support these extensions, and
  1471. so NASM cannot be used to write shared library code under ELF. NASM
  1472. also does not support the capability, in ELF, for specifying precise
  1473. alignment constraints on common variables.
  1474.  
  1475. Both `aout' and `elf' default to 32-bit assembly mode.
  1476.  
  1477. `coff' and `win32': Common Object File Format
  1478. ---------------------------------------------
  1479.  
  1480. The `coff' format generates standard Unix COFF object files, which
  1481. can be fed to (for example) the DJGPP linker. Its default output
  1482. filename, like the other Unix formats, is `filename.o'.
  1483.  
  1484. The `win32' format generates Microsoft Win32 (Windows 95 or
  1485. Intel-platform Windows NT) object files, which nominally use the
  1486. COFF standard, but in fact are not compatible. Its default output
  1487. filename is `filename.obj'.
  1488.  
  1489. `coff' and `win32' are not quite compatible formats, due to the fact
  1490. that Microsoft's interpretation of the term `relative relocation'
  1491. does not seem to be the same as the interpretation used by anyone
  1492. else. It is therefore more correct to state that Win32 uses a
  1493. _variant_ of COFF. The object files will not therefore produce
  1494. correct output when fed to each other's linkers. (I've tried it!)
  1495.  
  1496. In addition to this subtle incompatibility, Win32 also defines
  1497. extensions to basic COFF, such as a mechanism for importing symbols
  1498. from dynamic-link libraries at load time. NASM may eventually
  1499. support this extension in the form of a format-specific directive.
  1500. However, as yet, it does not. Neither the `coff' nor `win32' output
  1501. formats have any specific directives.
  1502.  
  1503. The Microsoft linker also has a small blind spot: it cannot
  1504. correctly relocate a relative CALL or JMP to an absolute address.
  1505. Hence all PC-relative CALLs or JMPs, when using the `win32' format,
  1506. must have targets which are relative to sections, or to external
  1507. symbols. You can't do
  1508.     call 0x123456
  1509. _even_ if you happen to know that there is executable code at that
  1510. address. The linker simply won't get the reference right; so in the
  1511. interests of not generating incorrect code, NASM will not allow this
  1512. form of reference to be written to a Win32 object file. (Standard
  1513. COFF, or at least the DJGPP linker, seems to be able to cope with
  1514. this contingency. Although that may be due to the executable having
  1515. a zero load address...)
  1516.  
  1517. Note also that Borland Win32 compilers reportedly do not use this
  1518. object file format: while Borland linkers will output Win32-COFF
  1519. type executables, their object format is the same as the old DOS OBJ
  1520. format. So if you are using a Borland compiler, don't use the
  1521. `win32' object format, just use `obj' and declare all your segments
  1522. as `USE32'.
  1523.  
  1524. Both `coff' and `win32' support, in addition to the three standard
  1525. section names `.text', `.data' and `.bss', the ability to define
  1526. your own sections. Currently (this may change in the future) you can
  1527. provide the options `text' (or `code'), `data' or `bss' to determine
  1528. the type of section. Win32 also allows `info', which is an
  1529. informational section type used by Microsoft C compilers to store
  1530. linker directives. So you can do:
  1531.  
  1532.     section .mysect code    ; defines an extra code section
  1533.  
  1534. or maybe, in Win32,
  1535.  
  1536.     section .drectve info   ; defines an MS-compatible directive section
  1537.     db '-defaultlib:LIBC -defaultlib:OLDNAMES '
  1538.  
  1539. to pass directives to the MS linker.
  1540.  
  1541. Both `coff' and `win32' default to 32-bit assembly mode.
  1542.  
  1543. `obj' and `os2': Microsoft 16-bit Object Module Format
  1544. ------------------------------------------------------
  1545.  
  1546. The `obj' format generates 16-bit Microsoft object files, suitable
  1547. for feeding to 16-bit versions of Microsoft C, and probably
  1548. TLINK as well (although that hasn't been tested). The Use32
  1549. extensions are supported.
  1550.  
  1551. `obj' defines no special segment names: you can call segments what
  1552. you like. Unlike the other formats, too, segment names are actually
  1553. defined as symbols, so you can write
  1554.  
  1555.     segment CODE
  1556.     mov ax,CODE
  1557.  
  1558. and get the _segment_ address of the segment, suitable for loading
  1559. into a segment register.
  1560.  
  1561. Segments can be declared with attributes:
  1562.  
  1563.     SEGMENT CODE PRIVATE ALIGN=16 CLASS=CODE OVERLAY=OVL2 USE16
  1564.  
  1565. You can specify segments to be PRIVATE, PUBLIC, COMMON or STACK;
  1566. their alignment may be any power of two from 1 to 256 (although only
  1567. 1, 2, 4, 16 and 256 are really supported, so anything else gets
  1568. rounded up to the next highest one of those); their class and
  1569. overlay names may be specified. You may also specify segments to be
  1570. USE16 or USE32. The defaults are PUBLIC ALIGN=1, no class, no
  1571. alignment, USE16.
  1572.  
  1573. You can also specify that a segment is _absolute_ at a certain
  1574. segment address:
  1575.  
  1576.     SEGMENT SCREEN ABSOLUTE=0xB800
  1577.  
  1578. The ABSOLUTE and ALIGN keywords are mutually exclusive.
  1579.  
  1580. The format-specific directive GROUP allows segment grouping: `GROUP
  1581. DGROUP DATA BSS' defines the group DGROUP to contain segments DATA
  1582. and BSS.
  1583.  
  1584. Segments are defined as part of their group by default: if variable
  1585. `var' is declared in segment `data', which is part of group
  1586. `dgroup', then the expression `SEG var' is equivalent to the
  1587. expression `dgroup', and the expression `var' evaluates to the
  1588. offset of the variable `var' relative to the beginning of the group
  1589. `dgroup'. You must use the expression `var WRT data' to get the
  1590. offset of the variable `var' relative to the beginning of its
  1591. _segment_.
  1592.  
  1593. NASM allows a segment to be part of more than one group (like A86,
  1594. and unlike TASM), but will generate a warning (unlike A86!).
  1595. References to the symbols in that segment will be resolved relative
  1596. to the _first_ group it is defined in.
  1597.  
  1598. The directive `UPPERCASE' causes all symbol, segment and group names
  1599. output to the object file to be uppercased. The actual _assembly_ is
  1600. still case sensitive.
  1601.  
  1602. To avoid getting tangled up in NASM's local label mechanism, segment
  1603. and group names have leading periods stripped when they are defined.
  1604. Thus, the directive `SEGMENT .text' will define a segment called
  1605. `text', which will clash with any other symbol called `text', and
  1606. you will _not_ be able to reference the segment base as `.text', but
  1607. only as `text'.
  1608.  
  1609. Common variables in OBJ files can be `near' or `far': currently,
  1610. NASM has a horribly grotty way to support that, which is that if you
  1611. specify the common variable's size as negative, it will be near, and
  1612. otherwise it will be far. The support isn't perfect: if you declare
  1613. a far common variable both in a NASM assembly module and in a C
  1614. program, you may well find the linker reports "mismatch in
  1615. array-size" or some such. The reason for this is that far common
  1616. variables are defined by means of _two_ size constants, which are
  1617. multiplied to give the real size. Apparently the Microsoft linker
  1618. (at least) likes both constants, not merely their product, to match
  1619. up. This may be fixed in a future release.
  1620.  
  1621. If the module you're writing is intended to contain the program
  1622. entry point, you can declare this by defining the special label
  1623. `..start' at the start point, either as a label or by EQU (although
  1624. of course the normal caveats about EQU dependency still apply).
  1625.  
  1626. `obj' has an unusual handling of assembly modes: instead of having a
  1627. global default for the whole file, there is a separate default for
  1628. each segment. Thus, each SEGMENT directive carries an implicit BITS
  1629. directive with it, which switches to 16-bit or 32-bit mode depending
  1630. on whether the segment is a Use16 or Use32 segment. If you want to
  1631. place 32-bit code in a Use16 segment, you can use an explicit `BITS
  1632. 32' override, but if you switch temporarily away from that segment,
  1633. you will have to repeat the override after coming back to it.
  1634.  
  1635. If you're trying to build a .COM application by linking several .OBJ
  1636. files together, you need to put `resb 0x100' at the front of the
  1637. code segment in the first object file, since otherwise the linker
  1638. will get the linking wrong.
  1639.  
  1640. OS/2 uses an almost exactly similar file format to DOS, with a
  1641. couple of differences, principally that OS/2 defines a pseudo-group
  1642. called FLAT, containing no segments, and every relocation is made
  1643. relative to that (so it would be equivalent to writing `label WRT
  1644. FLAT' in place of `label' _throughout_ your code). Since this would
  1645. be inconvenient to write code for, NASM implements the `os2' variant
  1646. on `obj', which provides this FLAT group itself and automatically
  1647. makes the default relocation format relative to FLAT.
  1648.  
  1649. NOTE TO OS/2 USERS: The OS/2 output format is new in NASM version
  1650. 0.95. It hasn't been tested on any actual OS/2 systems, and I don't
  1651. know for sure that it'll work properly. Any OS/2 users are
  1652. encouraged to give it a thorough testing and report the results to
  1653. me. Thanks!
  1654.  
  1655. `as86': Linux as86 (bin86-0.3)
  1656. ------------------------------
  1657.  
  1658. This output format attempts to replicate the format used to pass
  1659. data between the Linux x86 assembler and linker, as86 and ld86. Its
  1660. default file name, yet again, is `filename.o'. Its default
  1661. segment-size attribute is 16 bits.
  1662.  
  1663. `rdf': Relocatable Dynamic Object File Format
  1664. ---------------------------------------------
  1665.  
  1666. RDOFF was designed initially to test the object-file production
  1667. interface to NASM. It soon became apparent that it could be enhanced
  1668. for use in serious applications due to its simplicity; code to load
  1669. and execute an RDOFF object module is very simple. It also contains
  1670. enhancements to allow it to be linked with a dynamic link library at
  1671. either run- or load- time, depending on how complex you wish to make
  1672. your loader.
  1673.  
  1674. The `rdoff' directory in the NASM distribution archive contains
  1675. source for an RDF linker and loader to run under Linux.
  1676.  
  1677. `rdf' has a default segment-size attribute of 32 bits.
  1678.  
  1679. Debugging format: `dbg'
  1680. -----------------------
  1681.  
  1682. This output format is not built into NASM by default: it's for
  1683. debugging purposes. It produces a debug dump of everything that the
  1684. NASM assembly module feeds to the output driver, for the benefit of
  1685. people trying to write their own output drivers.
  1686.  
  1687. Common Problems
  1688. ===============
  1689.  
  1690. A few problems that people repeatedly ask me about are documented
  1691. here.
  1692.  
  1693. NASM's design philosophy of generating exactly the code the
  1694. programmer asks for, without second-guessing or re-interpreting, has
  1695. been known to cause confusion in a couple of areas.
  1696.  
  1697. Firstly, several people have complained that instructions such as
  1698. `add esp,4' are assembled in a form that allocates a full four-byte
  1699. offset field to store the `4' in, even though the instruction has a
  1700. shorter form with a single-byte offset field which would work in
  1701. this case. The answer is that NASM by design doesn't try to guess
  1702. which one of these forms you want: if you want one, you code one,
  1703. and if you want the other, you code the other. The other form is
  1704. `add esp, byte 4'.
  1705.  
  1706. Secondly, and similarly, I've had repeated questions about
  1707. conditional jumps. The simple `jne label', in NASM, translates
  1708. directly to the old 8086 form of the conditional jump, in which the
  1709. offset can be up to 128 bytes (or thereabouts) in either direction.
  1710. NASM won't automatically generate `je $+3 / jmp label' for labels
  1711. that are further away, and neither will it generate the 386 long-
  1712. offset form of the instruction. If you want the 386-specific
  1713. conditional jump that's capable of reaching anywhere in the same
  1714. segment as the jump instruction, you want `jne near label'. If you
  1715. want an 8086-compatible `je' over another `jmp', code one
  1716. explicitly, or define a macro to do so. NASM doesn't do either of
  1717. these things for you, again by design.
  1718.  
  1719. Bugs
  1720. ====
  1721.  
  1722. Apart from the missing features (correct OBJ COMMON support, ELF
  1723. alignment, ELF PIC support, etc.), there are no _known_ bugs.
  1724. However, any you find, with patches if possible, should be sent to
  1725. <jules@earthcorp.com> or <anakin@pobox.com>, and we'll try to fix
  1726. them.
  1727.  
  1728. Beware of Pentium-specific instructions: Intel have provided a macro
  1729. file for MASM, to implement the eight or nine new Pentium opcodes as
  1730. MASM macros. NASM does not generate the same code for the CMPXCHG8B
  1731. instruction as these macros do: this is due to a bug in the _macro_,
  1732. not in NASM. The macro works by generating an SIDT instruction (if I
  1733. remember rightly), which has almost exactly the right form, then
  1734. using ORG to back up a bit and do a DB over the top of one of the
  1735. opcode bytes. The trouble is that Intel overlooked (or MASM syntax
  1736. didn't let them allow for) the possibility that the SIDT instruction
  1737. may contain an 0x66 or 0x67 operand or address size prefix. If this
  1738. happens, the ORG will back up by the wrong amount, and the macro
  1739. will generate incorrect code. NASM gets it right. This, also, is not
  1740. a bug in NASM, so please don't report it as one. (Also please note
  1741. that the ORG directive in NASM doesn't work this way, and so you
  1742. can't do equivalent tricks with it...)
  1743.  
  1744. That's All Folks!
  1745. =================
  1746.  
  1747. Enjoy using NASM! Please feel free to send me comments, or
  1748. constructive criticism, or bug fixes, or requests, or general chat.
  1749.  
  1750. Contributions are also welcome: if anyone knows anything about any
  1751. other object file formats I should support, please feel free to send
  1752. me documentation and some short example files (in my experience,
  1753. documentation is useless without at _least_ one example), or even to
  1754. write me an output module. OS/2 object files, in particular, spring
  1755. to mind. I don't have OS/2, though.
  1756.  
  1757. Please keep flames to a minimum: I have had some very angry e-mails
  1758. in the past, condemning me for writing a useless assembler, that
  1759. output in no useful format (at the time, that was true), generated
  1760. incorrect code (several typos in the instruction table, since fixed)
  1761. and took up too much memory and disk space (the price you pay for
  1762. total portability, it seems). All these were criticisms I was happy
  1763. to hear, but I didn't appreciate the flames that went with them.
  1764. NASM _is_ still a prototype, and you use it at your own risk. I
  1765. _think_ it works, and if it doesn't then I want to know about it,
  1766. but I don't guarantee anything. So don't flame me, please. Blame,
  1767. but don't flame.
  1768.  
  1769. - Simon Tatham <anakin@pobox.com>, 21-Nov-96
  1770.